WebSockets

Enable real-time communication between clients and servers using WebSockets. Tools to create interactive and dynamic applications.

Eg WebSocket

function Deno.upgradeWebSocket

upgradeWebSocket(

request: Request,

options?: UpgradeWebSocketOptions,
): WebSocketUpgrade

Upgrade an incoming HTTP request to a WebSocket.

Given a Request, returns a pair of WebSocket and Response instances. The original request must be responded to with the returned response for the websocket upgrade to be successful.

Deno.serve((req) => {
  if (req.headers.get("upgrade") !== "websocket") {
    return new Response(null, { status: 501 });
  }
  const { socket, response } = Deno.upgradeWebSocket(req);
  socket.addEventListener("open", () => {
    console.log("a client connected!");
  });
  socket.addEventListener("message", (event) => {
    if (event.data === "ping") {
      socket.send("pong");
    }
  });
  return response;
});

If the request body is disturbed (read from) before the upgrade is completed, upgrading fails.

This operation does not yet consume the request or open the websocket. This only happens once the returned response has been passed to respondWith().

Parameters

request: Request

options: UpgradeWebSocketOptions

optional

Return Type

WebSocketUpgrade

interface Deno.UpgradeWebSocketOptions

Options which can be set when performing a Deno.upgradeWebSocket upgrade of a Request

Properties

protocol: string

optional

Sets the .protocol property on the client side web socket to the value provided here, which should be one of the strings specified in the protocols parameter when requesting the web socket. This is intended for clients and servers to specify sub-protocols to use to communicate to each other.

idleTimeout: number

optional

If the client does not respond to this frame with a pong within the timeout specified, the connection is deemed unhealthy and is closed. The close and error event will be emitted.

The unit is seconds, with a default of 30. Set to 0 to disable timeouts.

socket: import("node:net").Socket

optional

A node:net Socket from a node:http server's "upgrade" event. When provided, the WebSocket upgrade is performed over this existing TCP connection instead of through Deno.serve's built-in upgrade mechanism. The 101 Switching Protocols response is written automatically.

import http from "node:http";

const server = http.createServer();
server.on("upgrade", (req, socket, head) => {
  const { socket: ws } = Deno.upgradeWebSocket(
    new Request(`http://${req.headers.host}/`, {
      headers: req.headers as HeadersInit,
    }),
    { socket: socket as import("node:net").Socket, head },
  );
  ws.onmessage = (e) => ws.send(e.data);
});

head: Uint8Array

optional

Extra bytes already buffered by the HTTP parser that arrived with the upgrade request headers. This is the head Buffer from the node:http server's "upgrade" event and must be forwarded so those bytes are not lost.

interface Deno.WebSocketUpgrade

The object that is returned from a Deno.upgradeWebSocket request.

Properties

response: Response

The response object that represents the HTTP response to the client, which should be used to the RequestEvent .respondWith() for the upgrade to be successful.

socket: WebSocket

The WebSocket interface to communicate to the client via a web socket.