WebSocket

The WebSocket API of Azion Runtime: how a function accepts a WebSocket upgrade, opens an outbound connection, and where its events appear.

Last updated

View as Markdown Agent setup

The WebSocket API of Azion Runtime lets a function act as a WebSocket server or as a WebSocket client, and carry bidirectional traffic to backend services. The function itself accepts or opens the connection, which separates this API from WebSocket Proxy, where an application only carries the connection to a WebSocket server at your origin. Use the WebSocket API for real-time workloads such as chat, multiplayer games, telemetry dashboards, and AI inference streams.

Under azion dev, upgradeWebSocket and WebSocket are not defined. A call to upgradeWebSocket() throws ReferenceError: upgradeWebSocket is not defined, and new WebSocket() throws TypeError: WebSocket is not a constructor. Deployed, both globals are defined as functions.

Availability

The WebSocket API is available to customers with Business, Enterprise, or Mission-Critical Support, and to customers with a Reserved Capacity or Saving Plan contract. To request access, contact Technical Support.

Server and client modes

A deployed function reaches both modes through two globals:

GlobalModeDescription
upgradeWebSocket(request)ServerAccepts the WebSocket upgrade of an incoming request. Returns an object with response and socket: return response from the handler to complete the upgrade, and use socket to send and receive messages.
WebSocket(url)ClientThe standard WebSocket constructor. Opens an outbound WebSocket connection from the function to url.

upgradeWebSocket() accepts only a request whose upgrade header contains websocket. Called with any other request, it throws TypeError: Invalid Header: 'upgrade' header must contain 'websocket', so check the header before the call, as the example below does.

Azion Runtime also provides helpers that broadcast a message to every connected client, so one function can fan out a message to all of its connections.

Metrics and logs

WebSocket activity produces three events, which appear in Real-Time Metrics and Data Stream to help you monitor connections and messages:

  • websocket.connection.accepted
  • message.sent
  • message.received

Firewall inspection

The rules of a firewall can inspect WebSocket traffic before the upgrade completes. Check that your firewall rules let through the WebSocket connections that your function must accept.

Example

This handler accepts a WebSocket upgrade when the request carries upgrade: websocket, logs the open, message, close, and error events of the socket, and answers each message with pong. Any other request receives an HTML page whose script opens a WebSocket connection back to the same host:

JavaScript
01export default {
02 async fetch(request, env, ctx) {
03 // Check if the request is a WebSocket upgrade
04 if (request.headers.get("upgrade") === "websocket") {
05 // Use the upgradeWebSocket function to handle the WebSocket upgrade
06 const { response, socket } = upgradeWebSocket(request);
07
08 // Handle WebSocket events
09 socket.addEventListener("open", () => {
10 console.log("WebSocket connection established");
11 });
12
13 socket.addEventListener("message", (event) => {
14 console.log(`Message received: ${event.data}`);
15 socket.send("pong"); // Respond with "pong"
16 });
17
18 socket.addEventListener("close", () => {
19 console.log("WebSocket connection closed");
20 });
21
22 socket.addEventListener("error", (error) => {
23 console.error("WebSocket error:", error);
24 });
25
26 // Return the response to complete the WebSocket upgrade
27 return response;
28 }
29
30 // If the request is not a WebSocket upgrade, serve a simple HTML page
31 const htmlContent = `
32 <!DOCTYPE html>
33 <html>
34 <head>
35 <title>WebSocket Example</title>
36 </head>
37 <body>
38 <h1>WebSocket Example</h1>
39 <script>
40 const socket = new WebSocket("wss://" + location.host);
41 socket.onopen = () => console.log("WebSocket connected");
42 socket.onmessage = (event) => console.log("Message from server:", event.data);
43 socket.onclose = () => console.log("WebSocket disconnected");
44 socket.onerror = (error) => console.error("WebSocket error:", error);
45 </script>
46 </body>
47 </html>
48 `;
49
50 return new Response(htmlContent, {
51 status: 200,
52 headers: { "Content-Type": "text/html" },
53 });
54 },
55};

A deployed function returns this response to a request without the upgrade header. The body is the HTML page, with its line breaks escaped:

JSON
01{
02 "status": 200,
03 "statusText": "",
04 "headers": {
05 "content-type": "text/html"
06 },
07 "body": "\n <!DOCTYPE html>\n <html>\n <head>\n <title>WebSocket Example</title>\n </head>\n <body>\n <h1>WebSocket Example</h1>\n <script>\n const socket = new WebSocket(\"wss://\" + location.host);\n socket.onopen = () => console.log(\"WebSocket connected\");\n socket.onmessage = (event) => console.log(\"Message from server:\", event.data);\n socket.onclose = () => console.log(\"WebSocket disconnected\");\n socket.onerror = (error) => console.error(\"WebSocket error:\", error);\n </script>\n </body>\n </html>\n "
08}
WebSocket Proxy

How an application carries a WebSocket connection to a server at your origin.

Handlers

The handler shape that receives the request and returns the upgrade response.

Request

How a function reads the headers of the incoming request, such as upgrade.

Web APIs

The other Web APIs that Azion Runtime supports.