WebSocket

A WebSocket API do Azion Runtime: como uma function aceita um upgrade WebSocket, abre uma conexão de saída e onde os eventos dela aparecem.

Última atualização

Ver como Markdown Configurar agente

A WebSocket API do Azion Runtime permite que uma function atue como servidor ou como cliente WebSocket e transporte tráfego bidirecional para serviços de backend. A própria function aceita ou abre a conexão, o que diferencia esta API do WebSocket Proxy, em que uma aplicação apenas transporta a conexão até um servidor WebSocket na sua origem. Use a WebSocket API para cargas de trabalho em tempo real, como chat, jogos multiplayer, dashboards de telemetria e fluxos de inferência de AI.

nota — Com azion dev, upgradeWebSocket e WebSocket não estão definidos. Uma chamada a upgradeWebSocket() lança ReferenceError: upgradeWebSocket is not defined, e new WebSocket() lança TypeError: WebSocket is not a constructor. Em uma function com deploy feito, os dois globais estão definidos como funções.

Disponibilidade

A WebSocket API está disponível para clientes com Business, Enterprise ou Mission-Critical Support e para clientes com contrato de Reserva de Capacidade ou de Saving Plan. Para solicitar acesso, entre em contato com o suporte técnico.

Modos servidor e cliente

Uma function com deploy feito acessa os dois modos por meio de dois globais:

GlobalModoDescrição
upgradeWebSocket(request)ServidorAceita o upgrade WebSocket de uma requisição recebida. Retorna um objeto com response e socket: retorne response do handler para concluir o upgrade e use socket para enviar e receber mensagens.
WebSocket(url)ClienteO construtor padrão WebSocket. Abre uma conexão WebSocket de saída da function para url.

upgradeWebSocket() aceita apenas uma requisição cujo header upgrade contém websocket. Chamada com qualquer outra requisição, a função lança TypeError: Invalid Header: 'upgrade' header must contain 'websocket'. Por isso, verifique o header antes da chamada, como faz o exemplo abaixo.

O Azion Runtime também oferece helpers que fazem o broadcast de uma mensagem para todos os clientes conectados, de modo que uma function pode distribuir uma mensagem para todas as conexões dela.

Métricas e logs

A atividade WebSocket gera três eventos, que aparecem em Real-Time Metrics e em Data Stream para ajudar você a monitorar conexões e mensagens:

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

Inspeção pelo firewall

As regras de um firewall podem inspecionar o tráfego WebSocket antes que o upgrade seja concluído. Verifique se as regras do seu firewall deixam passar as conexões WebSocket que a sua function precisa aceitar.

Exemplo

Este handler aceita um upgrade WebSocket quando a requisição traz upgrade: websocket, registra em log os eventos open, message, close e error do socket e responde a cada mensagem com pong. Qualquer outra requisição recebe uma página HTML cujo script abre uma conexão WebSocket de volta para o mesmo 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};

Uma function com deploy feito retorna esta resposta a uma requisição sem o header upgrade. O corpo é a página HTML, com as quebras de linha escapadas:

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}

Recursos relacionados

WebSocket Proxy

Como uma aplicação transporta uma conexão WebSocket até um servidor na sua origem.

Handlers

O formato de handler que recebe a requisição e retorna a resposta de upgrade.

Request

Como uma function lê os headers da requisição recebida, como upgrade.

Web APIs

As outras Web APIs que o Azion Runtime suporta.