WebSocket API

[sergiodxa]

Proposal

Add built-in support for WebSockets to Remix.

Background

WebSockets are the most popular way to build real-time apps, and while SSE exists and Remix supports it out of the box, it's not so common and it's limited to one-way communication from server to client, which sometimes is desired and sometimes is not.

Use Case

• Real-time apps
• Avoid switching to Express if you use RAS
• Avoid creating a separate app for the WebSocket server

API/Examples

Remix could allow a socket import which let you mark a route as subscribable:

export async function socket() {
  /* ... */
}

This socket function will receive any data sent from the client or broadcasted from another part of the app.

To send data from the client you could use the useSocket hook, this will connect to the WebSocket channel associated to the route:

export default function Component() {
  let socket = useSocket();
  socket.emit("message", "ping");
  // ...
}

Now you can access this from your socket function:

export async function socket({ data }: SocketArgs) {
  /* ... */
}

Once a component unmounts the subscription should be closed.

Types

The SocketArgs could accept a generic to define what type of data it expects to receive, and the data property could be typed based on that.

type SocketData = string;

export async function socket({ data }: SocketArgs<SocketData>) {
  /* ... */
}

export default function Component() {
  let socket = useSocket<SocketData>(); // use same generic as socket function
  // ...
}

Broadcast from action

The data could also be broadcasted from an action function:

export async function action({ request, broadcast }: ActionArgs) {
  let formData = await request.formData();
  let something = await doSomething(formData);
  await broadcast<SocketData>("ping"); // this should pass data from action to the socket
  return json(null);
}

This will allow developers to keep using action for mutations, and then broadcast this to every user subscribed to the channel.

Broadcast from socket

This broadcast function will also be available on the socket function, this to enable clients to broadcast data to other clients subscribed to the same channel.

export async function socket({ data, broadcast }: SocketArgs<SocketData>) {
  broadcast(data);
}

The broadcast function will accept only the SocketData value, and will broadcast to the same channel.

Subscribe to different channels

A component could specify the channel to subscribe to:

export default function Component() {
  let socket = useSocket<AnotherSocketData>("/chats/1/messages/new");
  // ...
}

This way you can subscribe to different channels from the same component.

Broadcast to different channels

The broadcast function could also accept a path to broadcast to a different channel:

export async function socket({ data, broadcast }: SocketArgs<SocketData>) {
  broadcast<AnotherSocketData>(data, { channel: "/chats/1/messages/new" });
}

And the same will happen on the action function:

export async function action({ request, broadcast }: ActionArgs) {
  let formData = await request.formData();
  let something = await doSomething(formData);
  await broadcast<AnotherSocketData>("ping", { channel: "/chats/1/messages/new" });
  return json(null);
}

In both cases, broadcast will allow a generic to be passed to customize the expected data type, if this generic is not defined it must fallback to the SocketArgs generic inside a socket function.

Receive data from server

The socket object returned by useSocket will also let's you subscribe to the data from the server:

export default function Component() {
  let socket = useSocket<SocketData>();
  useEffect(() => {
    socket.on("message", listener);
    return () => socket.off("message", listener);
    function listener(data: SocketData) {
      /* ... */
    }
  }, [socket]);
}

As a convenience Remix could provide a useSocketData hook to be used like this:

export default function Component() {
  let data = useSocketData<SocketData>("/chats/1/messages/new");
  // ...
}

This will basically do the following:

function useSocketData<Type>(path?: string) {
  let [data, setData] = useState<Type | null>(null);
  let socket = useSocket<Type>(path);
  useEffect(() => {
    socket.on("message", setData);
    return () => socket.off("message", setData);
  }, [socket]);
  return data;
}

The return type will be Type | null to indicate that the data could be null if the socket is not connected yet or haven't received any value from the server.

The data will also always be the latest version, is up to the user to keep track of previous values if needed.

Open questions

• What should happen with servers that doesn't support WebSockets?
• Should this feature only be available on compatible server?

[andrelandgraf]

Maybe I am missing something here but how would the websocket API fit together with serverless targets like cloudflare workers or lambda function deployments? What happens when the remix server sleeps between requests, how would that fit together with websockets that always have to listen for messages?

[sergiodxa]

From Ryan's comment

ryanflorence — hoy a las 11:07
we'll have a table of "features supported by each adapter"
and if you try to use one with a platform that's not supported we'll throw

So yeah, it's something you are going to be able to use based on the adaptar you are using, if you use Express for example you can use it, Vercel or CF will not be able to use it.

Another option is to see if there are ways, maybe in the future, to enable it, maybe CF release a WebSocket feature you can use when deploying there and Remix can use that internally

[alexanderson1993]

CF does have websockets support via Durable Objects, so it's theoretically possible that the adapter could make them work that way.

[andrelandgraf]

That makes sense! The only reason my codebase is kind of complicated right now is because of a few ressource endpoints and the websocket server in my express app. If I could move that code into /app, I could get rid of my shared/ folder and manage everything in /app. Would love that!

[jgb-solutions]

@andrelandgraf hey, are you using Remix? And if so, how do you broadcast to the connected clients in your action(s)?

[andrelandgraf]

@jgb-solutions, sorry for the late response. I am using socket.io and the Remix express adapter. You can find more information about it in Sergio's blog here and an example implementation here.

[gavriguy]

Another option for serverless will be to add some logic to the client that will then ask to refetch data from the action. Maybe something on top of usefeatchers. It means that instead of using sockets to pass data it'll we be used only to tell the component to refetch. This also can integrate with long polling easily

[HeyGarrison]

Another option for serverless will be to add some logic to the client that will then ask to refetch data from the action. Maybe something on top of usefeatchers. It means that instead of using sockets to pass data it'll we be used only to tell the component to refetch. This also can integrate with long polling easily

This is the exact approach that SWR (stale-while-revalidate) takes and it powers Vercel's dashboard screen. It's not a bad approach considering the Javascript ecosystem is so tied into edge computing at this point.

[Jaikant]

Another option for serverless will be to add some logic to the client that will then ask to refetch data from the action. Maybe something on top of usefeatchers. It means that instead of using sockets to pass data it'll we be used only to tell the component to refetch. This also can integrate with long polling easily

This is the exact approach that SWR (stale-while-revalidate) takes and it powers Vercel's dashboard screen. It's not a bad approach considering the Javascript ecosystem is so tied into edge computing at this point.

Having real time data fetching/updates tied to the loaders is needed.
SWR uses polling, which is not 'real time'. A refetch like done in SWR is good to have, maybe that refetch should be triggered using a websocket?

[sergiodxa]

The problem is on Serverless you can't have a long running process, required to use WebSockets.

So in those scenarios a WebSocket feature will not be usable, and the only option you have is polling.

BTW, not all Serverless providers has this limit, Cloudflare can use WebSockets using DurableObjects.

[Jaikant]

Okay, which means the adapters should support websockets. But it also needs support within the useLoaders or Actions. Those changes could be part of core remix and not the adapters

[sergiodxa]

Yes this will need a change in two parts, first is the Remix changes itself, the new API to let the action broadcast changes and the components subscribe to WS messages, the second part is on the adapters where it should integrate with the server, and if the server can’t support WS show an error.

[Jaikant]

Sounds great. Is this on the roadmap by any chance?

[ngbrown]

Is it best practice to have your primary web application directly host the websocket endpoint, or should a message bus oriented back-end be handling traffic like that? Do we still need to worry about long-poll now that all the clients support websocket directly?

[Jaikant]

Is it best practice to have your primary web application directly host the websocket endpoint, or should a message bus oriented back-end be handling traffic like that? Do we still need to worry about long-poll now that all the clients support websocket directly?

I would prefer the loader to handle the websocket connection. Which implies the the websocket should be handled by the backend. I feel the loader is the ideal place for this, cause it returns data which is loaded by the component.

So the loader fetches the initial data, and also can push specific data into the component.

let realTimeData = useLoaderData();
// render messages here

[sergiodxa]

That will not work, loaders run server side only and run once, after you send a response the connection with the browser will be closed by the server.

[Jaikant]

@sergiodxa That may be the current behaviour.

From a developer experience perspective, I feel it is intuitive for the loader to be a loader for all different way of loading data into the component. Doesn't matter if it is first loading or later loading. Via pull (http) or push (sockets). That's what I feel.

[Jaikant]

Then a loader would look something like the below. The socket is the socket between the remix front/backend. Which would be available on the loader through remix.

const loader = ({ socket }) => {
      ...
       // Receive socket data from message bus on server, send to frontend.
       If (socketData) {
           socket.send({someData})
           return null
       }
       
       ....
        // Send data via http to frontend
	return json(someData);
}

And then the useLoader hook would be something like:

const [httpData, socketData] = useLoaderData()

[ngbrown]

If you need to scale the WS server separately from the HTTP server you'll probably don't use this feature directly and instead use a pub/sub or queue system to communicate between your Remix app and the WS to broadcast messages and manually (or with a lib) do the connection client-side.

I think because Remix, and modern apps in general, are focusing on distributed, at the edge, computing; features like WebSockets don't belong in the application server. A separate component that can focus on that ability in a scaled and resilient way should be used.

Should Remix take on every possible feature, or just the one it will be good at?

[sostenesapollo]

I've get that to work locally, but when I deploy at vercel it just does not connect to ws client via page

[kettanaito]

Hi! A nice proposal! Will share my feedback below.

This socket function will receive any data sent from the client or broadcasted from another part of the app.

I find this to be insufficient. True, in WebSocket connections you are mostly interested in the transferred data but there's much more to do there. For once, you can close the client (gracefully or with an error), observe the client's URL, binaryType, etc. all of which affects the way you communicate with the client.

Proposal: Instead of accepting data in the socket handler, accept the entire client, much like most WebSocket servers operate:

export const socket = ({ client }) => {
  client.addEventListener('message', (event) => {})
})

As a side effect, this makes the user learn more about the WHATWG WebSocket API by handling MessageEvent, and not an abstract data. You use the client reference to handle any client events, not just message, and you do so in the same way you do while using the standard WebSocket class.

To send data from the client you could use the useSocket hook, this will connect to the WebSocket channel associated to the route:

I fail to see a practical reason to bind a component with a WebSocket server on a route. Any route should be able to connect to your WebSocket server present on a particular route. The useSocket() hook looks redundant to me, especially because it effectively introduces a custom WebSocket client instead of letting Remix users use whichever client they want and need, like SocketIO.

The API is proposed on the assumption that the component's life-cycle and the WebSocket server's life-cycle are connected and dependent. I think that's not the case.

Proposal: Allow any client to connect to a WebSocket server established at a particular route. Allow any WebSocket clients to be used in a Remix app, don't lock it under a built-in useSocket().

The SocketArgs could accept a generic to define what type of data it expects to receive, and the data property could be typed based on that.

Data transferred over the WebSocket connection cannot be narrowed like that on a type-level. It's always a union of string | Blob | ArrayBuffer. Casting it to a string is overly optimistic and will cause issues without a runtime guard that the server actually received a string.

Proposal: Instead, consider adopting an EventMap model, where the user can describe the incoming (and outgoing!) WebSocket messages. Then, use that map purely in conjuncture with runtime message parsing.

type IncomingData =
  | { type: 'hello' }
  | { type: 'goodbye' }

type OutgoingData = 
  | { type: 'server/foo' }

What should happen with servers that doesn't support WebSockets?

Returning a "Protocol not supported" error response would be nice.

Should this feature only be available on compatible server?

What is a "compatible server"? Are we talking about the deployment targets, like Vercel, Cloudflare, etc? It would be great if Remix didn't bake that support map in itself and instead relied on the deployment target to determine that for the user.

---

It would be great to keep the set of all connected WebSocket clients in the argument to the socket function:

export const socket = ({ client, clients }) => {
  client // currently connected client
  clients // Set<Client>, all clients connected.
})

Also, consider WebSocketStream as a part of the feature set.

It would be natural to let the user handle the Upgrade request for the handshake phase of the WebSocket connection:

// app/routes/api/ws.ts

export const loader = ({ request }) => {
  return new Response(null, {
    status: 101,
    headers: {
      Upgrade: 'websocket',
      Connection: 'upgrade'
    }
  })
}

Perhaps this can even be used as a basic authorization layer to see which clients are even allowed to connect.

Another side effect: learning about how the WebSocket connections work!

Questions

• How would you handle the "room" concept?
• How would you handle authorization?

[kettanaito]

Remix can offer WebSocket support for standalone servers at first, and then decide how to transfer that to other targets. Do you think that would work? WebSocket and stateful go hand-in-hand, so perhaps serverless and WebSocket don't even combine behavior-wise.

[sergiodxa]

I do, I think the best approach is to make WS support be dependent of the platform where you deploy and then the team could document when is that feature supported.

[sergiodxa]

This part of your proposal:

// app/routes/api/ws.ts

export const loader = ({ request }) => {
  return new Response(null, {
    status: 101,
    headers: {
      Upgrade: 'websocket',
      Connection: 'upgrade'
    }
  })
}

Makes me think if maybe Remix could provide a custom response to use here to handle WS, similar to my eventStream response in Remix Utils package.

export async function loader({ request }: LoaderFunctionArgs) {
  // here you can do anything async like authentication, authorization, DB queries, etc.

  // the signal can be used to close the connection
  return socket(request.signal, {
    async onMessage(...args) {
      // here you can do thing when the server receives a message
    }
    // add more onSomething for other WS events
  })
}

Then Remix could use this socket response to do the upgrade and handle the WS connection for that route.

The thing with this approach would be that now the socket can only be used for resource routes, which could be ok, but my proposal adding a socket export to routes was more intended to let UI routes also support WS connections.

[sergiodxa]

Related to

Data transferred over the WebSocket connection cannot be narrowed like that on a type-level. It's always a union of string | Blob | ArrayBuffer. Casting it to a string is overly optimistic and will cause issues without a runtime guard that the server actually received a string.

Now that with Single Fetch feature Remix is implementing turbo-stream to allow sending more data types from the server to the browser, I think a WS feature could leverage it too, that would allow you to send plain JS objects, Date, Map, etc. Even Promise instances although I'm not sure how it could stream it.

An interesting side effect once RSC is supported is that turbo-stream would allow you to send JSX over WS, subscribing to a WS endpoint and getting new UIs could be a great feature, you could even send new client components references over WS so the browser could load them.

[kettanaito]

@sergiodxa, not sure I like the socket(signal, { onMessage }) API. I've never seen it used like this anywhere. The closer the Remix API is to how one writes an actual WebSocket server, the better. Responding with "Switching protocols" sound like a sensible thing to do because that's what the server should do per spec.

Not sure what the signal would do here. You cannot terminate anything server-side, unless I'm reading this wrong. You can only close incoming clients, but that's done via client.close(code, reason).

that would allow you to send plain JS objects, Date, Map, etc. Even Promise instances although I'm not sure how it could stream it.

I would not advise to implement anything outside of the WHATWG standard that's user-facing. Internally, Remix can send quite anything but the user should have a source of truth to look at, which is the spec. Remix wraps the JSX streaming into RSC anyway, I can hardly think when the user would want to stream a JSX over a WebSocket connection, to be frank. Perhaps guarding the user against that is, in itself, a good idea.