WebSockets en un Durable Object: el hogar del tiempo real

Todo lo que has construido hasta aquí obedece a un compás de dos tiempos: el cliente pide, el servidor responde, y la conexión se despide. Es el ritmo de HTTP, perfecto para servir una página o devolver un JSON. Pero hay una clase de aplicaciones que ese compás no sabe tocar: las que ocurren en vivo. En un chat, en un documento compartido, en una partida, el servidor tiene que hablar cuando nadie le ha preguntado, y todos los presentes deben oír lo mismo a la vez. El WebSocket abre ese canal permanente y bidireccional; pero un canal necesita dos extremos que perduren, y un Worker, que nace y muere con la petición, no puede sostener el suyo. Hace falta algo que viva, que recuerde quién está conectado y que ponga a todos en la misma sala. Ese algo ya lo conoces.

El límite del pedir-y-responder

HTTP es una conversación por turnos. Cada petición abre una conexión, lleva una pregunta, recibe una respuesta y se cierra; el servidor nunca habla primero. Para servir contenido eso es una virtud, pero para el tiempo real es una camisa de fuerza. El apaño clásico es el sondeo: el cliente vuelve a preguntar una y otra vez —“¿hay algo nuevo?, ¿y ahora?”—, un desperdicio de peticiones que además llega siempre tarde, al ritmo del reloj y no al de los hechos.

El WebSocket resuelve el problema de raíz. La conexión empieza como una petición HTTP normal, pero con dos cabeceras que anuncian un cambio de intención: Upgrade: websocket y Connection: Upgrade. El servidor, en vez de responder un 200 con un cuerpo, contesta 101 Switching Protocols, y desde ese instante la misma conexión TCP deja de hablar HTTP y empieza a hablar el protocolo de tramas de WebSocket. No se abre una conexión nueva: se transforma la que ya había. A partir de ahí el turno desaparece —ambos extremos envían cuando quieren, mientras el canal siga vivo.

Esa metamorfosis es la clave. Lo que llega al servidor es, al principio, una petición HTTP como cualquier otra, y por eso puede enrutarse con las mismas herramientas que ya dominas. Pero lo que queda después no es una respuesta: es un tubo abierto que alguien tiene que sostener por el lado del servidor. Y ahí aparece el problema que define este nivel entero.

Por qué el objeto es el otro extremo

Un WebSocket tiene dos extremos y los dos deben perdurar. El del cliente vive en el navegador, sin misterio. El del servidor es el difícil: algo tiene que mantener ese socket abierto, recordarlo y —lo decisivo— coordinarlo con los demás sockets de la misma sala. Un Worker sin estado no puede: está diseñado para morir con la petición. Y aunque pudiera sostener un socket, dos usuarios del mismo chat podrían caer en dos isolates distintos en dos continentes, cada uno con media sala en la mano y ninguno capaz de alcanzar al otro. El broadcast se vuelve imposible porque no hay un solo lugar donde converjan todas las conexiones.

El Durable Object es exactamente ese lugar único. Es único —una instancia por nombre, y todos aterrizan en la misma—; persiste —vive entre mensaje y mensaje, y sostiene los sockets en su memoria—; y es de un solo hilo —serializa los eventos, así que el estado de la sala nunca se corrompe—. Las tres propiedades que lo hicieron el actor del estado coordinado lo convierten, sin añadir nada, en el actor de las conexiones coordinadas. Una sala es un Durable Object; los sockets de todos sus miembros los guarda ese objeto; difundir es recorrerlos uno a uno.

WebSocketPair: abrir el canal

Vayamos a la mecánica. El upgrade llega al Worker como una petición normal; el Worker reconoce la cabecera y reenvía la petición entera al objeto por fetch —este es el caso en que fetch, y no el RPC, es la puerta, porque lo que viaja es literalmente una petición HTTP—. Dentro del objeto no aceptas el socket del cliente directamente: acuñas una pareja con WebSocketPair, dos sockets enlazados, uno que te quedas —el extremo servidor— y otro que devuelves al cliente dentro de la respuesta 101.

export class Sala extends DurableObject {
  async fetch(request: Request): Promise<Response> {
    const par = new WebSocketPair();
    const [cliente, servidor] = Object.values(par);
    servidor.accept();
    return new Response(null, { status: 101, webSocket: cliente });
  }
}

new WebSocketPair() devuelve un objeto con dos sockets enlazados: el 0, el del cliente, y el 1, el del servidor. Object.values los desempaqueta. La llamada servidor.accept() le dice al runtime que el objeto se hace cargo de ese extremo y queda listo para recibir. La respuesta es un 101 sin cuerpo con un campo especial, webSocket, que lleva el extremo del cliente de vuelta por el cable hasta el navegador. Desde ese momento el objeto sostiene un extremo y el navegador el otro: el tubo está abierto.

Del lado del Worker, el enrutado convierte el nombre de la sala en la identidad del objeto:

export default {
  async fetch(request, env): Promise<Response> {
    if (request.headers.get("Upgrade") !== "websocket") {
      return new Response("Se esperaba un WebSocket", { status: 426 });
    }
    const id = env.SALA.idFromName("sala:general");
    return env.SALA.get(id).fetch(request);
  },
} satisfies ExportedHandler<Env>;

Todo el que se conecta a sala:general cae en el mismo objeto, y allí sus sockets se encuentran. El nombre es la sala: cámbialo por el identificador de un documento, de una partida o de un usuario, y tendrás tantas salas como nombres sepas acuñar.

sequenceDiagram
participant C as Cliente
participant W as Worker
participant DO as Objeto Sala
C->>W: GET con Upgrade websocket
W->>DO: fetch reenvia la peticion entera
DO-->>C: 101 y el canal queda abierto
C-->>DO: mensajes en los dos sentidos