Skip to content
Cloudflare Docs

Durable Object Base Class

The DurableObject base class is an abstract class which all Durable Objects inherit from. This base class provides a set of optional methods, frequently referred to as handler methods, which can respond to events, for example a webSocketMessage when using the WebSocket Hibernation API. To provide a concrete example, here is a Durable Object MyDurableObject which extends DurableObject and implements the fetch handler to return "Hello, World!" to the calling Worker.

JavaScript
export class MyDurableObject extends DurableObject {
  constructor(ctx, env) {
    super(ctx, env);
  }


  async fetch(request) {
    return new Response("Hello, World!");
  }
}

Methods

fetch

  • fetch(request Request): Response | Promise<Response>

    • Takes an HTTP Request ↗ and returns an HTTP Response ↗. This method allows the Durable Object to emulate an HTTP server where a Worker with a binding to that object is the client.

    • This method can be async.

    • Durable Objects support RPC calls as of compatibility date 2024-04-03. RPC methods are preferred over fetch() when your application does not follow HTTP request/response flow.

Parameters

  • request Request - the incoming HTTP request object.

Return values

  • A Response or Promise<Response>.

Example

JavaScript
export class MyDurableObject extends DurableObject {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/hello") {
      return new Response("Hello, World!");
    }
    return new Response("Not found", { status: 404 });
  }
}

alarm

  • alarm(alarmInfo? AlarmInvocationInfo): void | Promise<void>

    • Called by the system when a scheduled alarm time is reached.

    • The alarm() handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception.

    • This method can be async.

    • Refer to Alarms for more information.

Parameters

  • alarmInfo AlarmInvocationInfo (optional) - an object containing retry information:
    • retryCount number - the number of times this alarm event has been retried.
    • isRetry boolean - true if this alarm event is a retry, false otherwise.

Return values

  • None.

Example

JavaScript
export class MyDurableObject extends DurableObject {
  async alarm(alarmInfo) {
    if (alarmInfo?.isRetry) {
      console.log(`Alarm retry attempt ${alarmInfo.retryCount}`);
    }
    await this.processScheduledTask();
  }
}

webSocketMessage

  • webSocketMessage(ws WebSocket, message string | ArrayBuffer): void | Promise<void>

    • Called by the system when an accepted WebSocket receives a message.

    • This method is not called for WebSocket control frames. The system will respond to an incoming WebSocket protocol ping ↗ automatically without interrupting hibernation.

    • This method can be async.

Parameters

  • ws WebSocket - the WebSocket ↗ that received the message. Use this reference to send responses or access serialized attachments.
  • message string | ArrayBuffer - the message data. Text messages arrive as string, binary messages as ArrayBuffer.

Return values

  • None.

Example

JavaScript
export class MyDurableObject extends DurableObject {
  async webSocketMessage(ws, message) {
    if (typeof message === "string") {
      ws.send(`Received: ${message}`);
    } else {
      ws.send(`Received ${message.byteLength} bytes`);
    }
  }
}

webSocketClose

  • webSocketClose(ws WebSocket, code number, reason string, wasClean boolean): void | Promise<void>

    • Called by the system when a WebSocket connection is closed.

    • You must call ws.close(code, reason) inside this handler to complete the WebSocket close handshake. Failing to reciprocate the close will result in 1006 errors on the client, representing an abnormal closure per the WebSocket specification.

    • This method can be async.

Parameters

  • ws WebSocket - the WebSocket ↗ that was closed.
  • code number - the WebSocket close code ↗ sent by the peer (e.g., 1000 for normal closure, 1001 for going away).
  • reason string - a string indicating why the connection was closed. May be empty.
  • wasClean boolean - true if the connection closed cleanly with a proper closing handshake, false otherwise.

Return values

  • None.

Example

JavaScript
export class MyDurableObject extends DurableObject {
  async webSocketClose(ws, code, reason, wasClean) {
    // Complete the WebSocket close handshake
    ws.close(code, reason);
    console.log(`WebSocket closed: code=${code}, reason=${reason}`);
  }
}

webSocketError

  • webSocketError(ws WebSocket, error unknown): void | Promise<void>

    • Called by the system when a non-disconnection error occurs on a WebSocket connection.

    • This method can be async.

Parameters

  • ws WebSocket - the WebSocket ↗ that encountered an error.
  • error unknown - the error that occurred. May be an Error object or another type depending on the error source.

Return values

  • None.

Example

JavaScript
export class MyDurableObject extends DurableObject {
  async webSocketError(ws, error) {
    const message = error instanceof Error ? error.message : String(error);
    console.error(`WebSocket error: ${message}`);
  }
}

Properties

ctx

ctx is a readonly property of type DurableObjectState providing access to storage, WebSocket management, and other instance-specific functionality.

env

env contains the environment bindings available to this Durable Object, as defined in your Wrangler configuration.