base.mdx

title	Durable Object Base Class
pcx_content_type	concept
sidebar	order 1

import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo, TypeScriptExample, } from "~/components";

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.

```ts export class MyDurableObject extends DurableObject { constructor(ctx: DurableObjectState, env: Env) { super(ctx, env); }

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

}

</TypeScriptExample>

<TabItem label="Python" icon="seti:python">

```python
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 ) : | - 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 - the incoming HTTP request object.

Return values

• A or .

Example

```ts export class MyDurableObject extends DurableObject { async fetch(request: Request): Promise { 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? ) : |
  • 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 (optional) - an object containing retry information:
  • retryCount - the number of times this alarm event has been retried.
  • isRetry - true if this alarm event is a retry, false otherwise.

Return values

• None.

Example

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

webSocketMessage

• webSocketMessage(ws , message ) : | - 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 - the WebSocket that received the message. Use this reference to send responses or access serialized attachments.
• message - the message data. Text messages arrive as string, binary messages as ArrayBuffer.

Return values

• None.

Example

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

webSocketClose

• webSocketClose(ws , code , reason , wasClean ) : | - 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 - the WebSocket that was closed.
• code - the WebSocket close code sent by the peer (e.g., 1000 for normal closure, 1001 for going away).
• reason - a string indicating why the connection was closed. May be empty.
• wasClean - true if the connection closed cleanly with a proper closing handshake, false otherwise.

Return values

• None.

Example

```ts export class MyDurableObject extends DurableObject { async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) { // With web_socket_auto_reply_to_close (compat date >= 2026-04-07), // the runtime has already completed the close handshake. // On older compat dates, call ws.close(code, reason) here. ws.close(code, reason); console.log(`WebSocket closed: code=${code}, reason=${reason}`); } } ```

webSocketError

• webSocketError(ws , error ) : | - Called by the system when a non-disconnection error occurs on a WebSocket connection. - This method can be async.

Parameters

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

Return values

• None.

Example

```ts export class MyDurableObject extends DurableObject { async webSocketError(ws: WebSocket, error: unknown) { 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.

Related resources

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