WebSockets

Enabling WebSockets

To use WebSockets in your scripts, you’ll first need to enable it for your Pull Zone in the Dashboard.

Navigate to your Pull Zone -> General -> WebSockets
Toggle the “WebSockets” switch
Call request.upgradeWebSocket() in your script to upgrade incoming connections

Quickstart

This example creates a WebSocket server that echoes messages back to the client.

import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http.serve(async (request: Request) => {
  const { response, socket } = request.upgradeWebSocket();

  socket.addEventListener("open", () => {
    console.log("Client connected");
  });

  socket.addEventListener("message", (event) => {
    console.log("Received:", event.data);
    socket.send(`Echo: ${event.data}`);
  });

  const closed = new Promise<void>((resolve) => {
    socket.addEventListener("close", (event) => {
      console.log("Client disconnected:", event.code, event.reason);
      resolve();
    });
  });

  // It is important to call waitUntil; otherwise the script may be evicted
  // while the WebSocket connection is still open.
  Bunny.v1.waitUntil(closed);

  return response;
});

upgradeWebSocket

Upgrades an incoming HTTP request to a WebSocket connection.

const { response, socket } = request.upgradeWebSocket();

// With options
const { response, socket } = request.upgradeWebSocket({
  protocol: "graphql-ws",
  idleTimeout: 60,
});

Parameters

string

The WebSocket subprotocol to use for the connection.

number

default:"30"

The number of seconds to wait for a pong response before closing the connection. If the client does not respond within this timeout, the connection is deemed unhealthy and closed, emitting the close and error events. If no data is transmitted from the client for 2 minutes, the connection will be closed regardless of this configuration.

Returns

Response

required

The response to send back to the client to establish the upgrade.

WebSocket

required

The WebSocket interface to communicate with the client.

Methods

close

Closes the WebSocket connection, optionally providing a close code and reason.

// Close normally
socket.close();

// Close with a code
socket.close(1000);

// Close with a code and reason
socket.close(1000, "Session ended");

Parameters

number

A standardized WebSocket close code. If unset, defaults to 1000 for normal closure or 1001-1015 for error conditions.

string

A human-readable close reason explaining why the connection was closed.

send

Transmits data to the connected client.

// Send a string
socket.send("Hello, client!");

// Send JSON
socket.send(JSON.stringify({ type: "message", content: "Hello" }));

// Send binary data
const buffer = new ArrayBuffer(8);
socket.send(buffer);

// Send a Blob
const blob = new Blob(["Hello"], { type: "text/plain" });
socket.send(blob);

Parameters

string | ArrayBufferLike | Blob | ArrayBufferView

required

The data to transmit. Can be a string, ArrayBufferLike, Blob, or ArrayBufferView.

addEventListener

Registers an event listener for WebSocket events.

socket.addEventListener("open", () => {
  console.log("Connection established");
});

socket.addEventListener("message", (event) => {
  console.log("Message received:", event.data);
});

socket.addEventListener("close", (event) => {
  console.log("Connection closed:", event.code, event.reason);
});

socket.addEventListener("error", (event) => {
  console.error("WebSocket error occurred");
});

Parameters

string

required

The event type to listen for. One of: open, message, close, or error.

function

required

The callback function invoked when the event is dispatched.

boolean | AddEventListenerOptions

Optional configuration for the event listener.

Events

open

Fired when the WebSocket connection is successfully established.

socket.addEventListener("open", (event) => {
  console.log("Connected to client");
  socket.send("Welcome!");
});

Event

A standard Event object with no additional properties.

message

Fired when a message is received from the client.

socket.addEventListener("message", (event) => {
  const data = event.data;

  // Handle string messages
  if (typeof data === "string") {
    const parsed = JSON.parse(data);
    console.log("Received:", parsed);
  }
});

object

Hide properties

any

required

The message data sent by the client.

string

The origin of the message.

string

The last event ID string.

MessageEventSource | null

The message source.

ReadonlyArray<MessagePort>

Any transferred ports.

close

Fired when the WebSocket connection is closed.

socket.addEventListener("close", (event) => {
  if (event.wasClean) {
    console.log(`Connection closed cleanly: ${event.code} ${event.reason}`);
  } else {
    console.log("Connection terminated unexpectedly");
  }
});

object

Hide properties

number

required

The WebSocket close code provided by the server.

string

required

The close reason provided by the server.

boolean

required

Whether the connection closed cleanly.

error

Fired when an error occurs on the WebSocket connection.

socket.addEventListener("error", (event) => {
  console.error("WebSocket error occurred");
});

Event

A standard Event object with no additional properties.

Documentation

Script Types

Deployment

Observability

APIs

Reference

Enabling WebSockets

Quickstart

upgradeWebSocket

Parameters

Returns

Methods

close

Parameters

send

Parameters

addEventListener

Parameters

Events

open

message

close

error

References

​Enabling WebSockets

​Quickstart

​upgradeWebSocket

​Parameters

​Returns

​Methods

​close

​Parameters

​send

​Parameters

​addEventListener

​Parameters

​Events

​open

​message

​close

​error

​References

Enabling WebSockets

Quickstart

upgradeWebSocket

Parameters

Returns

Methods

close

Parameters

send

Parameters

addEventListener

Parameters

Events

open

message

close

error

References