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.

from workers import DurableObject, Response

class MyDurableObject(DurableObject):
	def __init__(self, ctx, env):
		super().__init__(ctx, env)

	async def fetch(self, request):
		return 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

from workers import DurableObject, Response
from urllib.parse import urlparse

class MyDurableObject(DurableObject):
    async def fetch(self, request):
        path = urlparse(request.url).path
        if path == "/hello":
            return Response("Hello, World!")
        return 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

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def alarm(self, alarm_info=None):
        if alarm_info and alarm_info.isRetry:
            print(f"Alarm retry attempt {alarm_info.retryCount}")
        await self.process_scheduled_task()

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

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketMessage(self, ws, message):
        if isinstance(message, str):
            ws.send(f"Received: {message}")
        else:
            ws.send(f"Received {len(message)} bytes")

webSocketClose

• webSocketClose(ws WebSocket, code number, reason string, wasClean boolean) : void | Promise<void>- Called by the system when a WebSocket connection is closed.
  • With the web_socket_auto_reply_to_close compatibility flag (enabled by default on compatibility dates on or after 2026-04-07), the runtime automatically sends a reciprocal Close frame and transitions readyState to CLOSED before this handler is called. You do not need to call ws.close() — but doing so is safe (the call is silently ignored).
  • On older compatibility dates (before 2026-04-07), 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

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketClose(self, ws, code, reason, was_clean):
        ws.close(code, reason)
        print(f"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

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketError(self, ws, error):
        print(f"WebSocket error: {error}")

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.

Related resources

• Use WebSockets for WebSocket handler best practices.
• Alarms API for scheduling future work.
• RPC methods for type-safe method calls.